Summary

This PR adds an optional metadata parameter to both score_current_span and score_current_trace methods, bringing these convenience methods to feature parity with the underlying create_score method which already supports metadata.

Changes

• Added metadata: Optional[Any] = None parameter to all overloads of score_current_span
• Added metadata: Optional[Any] = None parameter to all overloads of score_current_trace
• Updated docstrings to document the new parameter
• Updated code examples in docstrings to demonstrate metadata usage
• Passed metadata parameter through to create_score calls

Motivation

The create_score method already supports attaching metadata to scores, but the convenience methods score_current_span and score_current_trace did not expose this parameter. This made it impossible to attach metadata when using these convenience methods without falling back to the lower-level create_score API.

Example Usage

Before (not possible):

langfuse.score_current_span(
    name="relevance",
    value=0.85,
    data_type="NUMERIC",
    comment="Mostly relevant"
)
# No way to add metadata!

After:

langfuse.score_current_span(
    name="relevance",
    value=0.85,
    data_type="NUMERIC",
    comment="Mostly relevant",
    metadata={"model": "gpt-4", "prompt_version": "v2"}
)

Test plan

• Verified parameter signatures are correct with proper type hints
• Verified docstrings are updated
• Verified metadata is passed through to create_score
• Integration tests should pass (existing tests continue to work as metadata is optional)

Disclaimer: Experimental PR review

Greptile Summary

Added optional metadata parameter to score_current_span and score_current_trace convenience methods, bringing them to feature parity with the underlying create_score method.

Key Changes:

• Added metadata: Optional[Any] = None parameter to all overloads and implementations of both methods
• Updated docstrings to document the new parameter with usage examples
• Passed metadata parameter through to underlying create_score calls
• Changes are fully backward compatible as metadata is optional

Impact:

• Users can now attach metadata to scores when using convenience methods without falling back to the lower-level create_score API
• Existing code continues to work as metadata defaults to None
• API is now consistent across all score creation methods

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are straightforward and follow existing patterns. The metadata parameter is already supported in create_score and ScoreBody, so this PR simply exposes it through convenience methods. All parameter additions are optional with default None values, ensuring backward compatibility. The implementation correctly passes metadata through to the underlying create_score calls. Existing tests will continue to pass since metadata is optional.
• No files require special attention

Important Files Changed

Sequence Diagram

sequenceDiagram
    participant User
    participant score_current_span
    participant score_current_trace
    participant create_score
    participant ScoreBody
    participant ResourceManager

    User->>score_current_span: score_current_span(name, value, metadata, ...)
    score_current_span->>score_current_span: Get current span context
    score_current_span->>score_current_span: Extract trace_id and observation_id
    score_current_span->>create_score: create_score(trace_id, observation_id, name, value, metadata, ...)
    
    User->>score_current_trace: score_current_trace(name, value, metadata, ...)
    score_current_trace->>score_current_trace: Get current span context
    score_current_trace->>score_current_trace: Extract trace_id
    score_current_trace->>create_score: create_score(trace_id, name, value, metadata, ...)
    
    create_score->>ScoreBody: new ScoreBody(id, traceId, observationId, name, value, metadata, ...)
    ScoreBody-->>create_score: ScoreBody instance
    create_score->>create_score: Create score event
    create_score->>ResourceManager: add_score_task(event)
    ResourceManager-->>create_score: Task queued
    create_score-->>User: Score created